home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / src / exampleCode / audio / DAT / README.dodat < prev    next >
Encoding:
Text File  |  1994-08-02  |  8.1 KB  |  199 lines
  1. DODAT: A simple DAT command interface
  2.  
  3. dodat is a simple program for creating DAT tapes from disk files, and
  4. extracting disk files from DAT tapes. It allows you to specify the exact 
  5. format of the DAT tape: what goes where, what program and index numbers are 
  6. used for each track, how much silence is between the tracks, lead-in and 
  7. lead-out areas, etc. 
  8.  
  9. dodat takes one option: -q, which tells it to be quiet. Normally it 
  10. spews constant feedback about what it's doing.
  11.  
  12. You can specify the name of a script to read as an argument to dodat.
  13.  
  14. Dodat's command parser is very simple and not very tolerant of errors. dodat 
  15. supports the following commands:
  16.  
  17. (BOT = beginning-of-tape; EOT = end-of-tape).
  18.  
  19. #     A comment. Anything following a '#' on a line is ignored.
  20.  
  21. quit    
  22.     quit the program.
  23.  
  24. leadin    
  25.     write a "lead-in" area at the current tape location.
  26.     This is 100 frames of silence in which the program number is
  27.     0xB (indicating BOT) and the timecodes are marked as invalid.
  28.  
  29.     Resets the program and index numbers.
  30.  
  31. leadout
  32.     write a "lead-out" area at the current tape location.
  33.     This is 300 frames of silence in which the program number is
  34.     0xE (indicating EOT) and the timecodes are marked as invalid.
  35.     When datman encounters an area such as this during a seek or
  36.     play, it stops the tape.
  37.  
  38.     You should not issue writes after the leadout area on the tape --
  39.     dodat will get confused.
  40.  
  41. write <filename>
  42.     Write the given file to the tape at the current location. The
  43.     current index and program numbers will be used; atime and ptime
  44.     will be incremented from the current values.
  45.  
  46. read <filename> <prognum>
  47.     Read from the current location on the tape into the given file.
  48.     Stop as soon as program <prognum> is encountered, without reading
  49.     any of <prognum> into the file. The sample rate written on the tape
  50.     will be used to mark the file.
  51.  
  52.     The read command skips over tape areas marked as BOT (beginning
  53.     of tape).
  54.  
  55. read <filename> <h>:<m>:<s>:<f>
  56.     Read from the current location on the tape into the given file.
  57.     Stop as soon as a-time given by {h,m,s,f} is encountered, without 
  58.     writing that frame into the file. The sample rate written on the tape
  59.     will be used to mark the file.
  60.  
  61.     The read command skips over tape areas marked as BOT (beginning
  62.     of tape).
  63.  
  64. silence <nframes>
  65.     Write the specified number of frames of silence to the tape, starting 
  66.     at the current position. Note that, following a seek or a read, dodat
  67.     must determine its current position in order to write the correct 
  68.     timecodes with the silence. 
  69.  
  70.     If you just issued a seek, dodat will need to read a frame to get
  71.     the correct position. Since writes following reads do not work 
  72.     properly, it will then seek back to the location it was just at,
  73.     write the frame it just read back to the tape, and then begin
  74.     writing the silence.
  75.  
  76.     If you just issued a read, dodat knows the correct position, but
  77.     it cannot immediately do a write, because writes following reads do 
  78.     not work properly. It will seek back to the location of the
  79.     frame you just read, write that frame back to the tape, and then begin
  80.     writing the silence.
  81.  
  82. testpat <nframes>
  83.     Write the specified number of frames of test-pattern to the tape, 
  84.     starting at the current position. Note that, following a seek or a 
  85.     read, dodat must determine its current position in order to write the 
  86.     correct timecodes with the test-pattern. See the notes under 'silence.'
  87.  
  88.     The test-pattern is used only by the verifydat program (with the
  89.     -t option) to verify the data on the tape as well as the timecode.
  90.  
  91. seek bot
  92.     rewind the tape.
  93.  
  94. seek at <h>:<m>:<s>:<f>
  95.     Seek to the absolute time given by the quadruple {h,m,s,f}. h is the
  96.     number of hours, m is the number of minutes, s is the number of
  97.     seconds, and f is the number of frames. See the section "About
  98.     DAT Timecode" for more information.
  99.  
  100. seek pt <h>:<m>:<s>:<f>
  101.     Seek to the program time, within the current program,  given by the 
  102.     quadruple {h,m,s,f}. h is the number of hours, m is the number of 
  103.     minutes, s is the number of seconds, and f is the number of frames. 
  104.     See the section "About DAT Timecode" for more information.
  105.  
  106. seek pn <n>
  107.     Seek to the beginning of program n. 
  108.  
  109. readframe
  110.     Read a single frame of audio from the tape, decode the timecodes, and
  111.     print them. Since this moves the tape, the actual tape position will 
  112.     be immediately AFTER the timecodes printed. In other words, suppose
  113.     you have just seeked to atime 0:0:5:0. If you do a readframe, 
  114.     it will print atime 0:0:5:0, since that was the frame read from the 
  115.     tape. However, your actual position following the readframe will be
  116.     0:0:5:1.
  117.  
  118.     This is strictly for diagnostic purposes.
  119.  
  120. readpos
  121.     Issue a read position command to the drive and print out what it says.
  122.     This does not move the tape.
  123.     NOTE: for current firmware revisions, this value will be incorrect. You
  124.     must use 'readframe' to get the correct tape position.
  125.  
  126.     This is strictly for diagnostic purposes.
  127.  
  128. program [n]
  129.     Set the program number to n. This number will be used on subsequent
  130.     write operations. This does not move the tape.
  131.  
  132.     If n is omitted, dodat increments the program number. This allows
  133.     you to make scripts, insert new programs in the middle of the script,
  134.     and have the remaining program numbers automatically corrected.
  135.  
  136. index [n]
  137.     Set the index number to n. This number will be used on subsequent
  138.     write operations. This does not move the tape.
  139.  
  140.     Index 0 has special meaning: it is reserved for inter-program
  141.     spacing, and program-time remains zero during this interval.
  142.  
  143.     If n is omitted, dodat increments the index number. This allows
  144.     you to make scripts, insert new things in the middle of the script,
  145.     and have the remaining index numbers automatically corrected.
  146.  
  147. rate <r>
  148.     Sets the sample rate to r. r must be one of {32,44,48}, corresponding
  149.     to the DAT sample rates of 32kHz, 44.1kHz, and 48 kHz, respectively.
  150.     This rate will be used on subsequent writes. The default is 44.1kHz.
  151.  
  152. prohibit <b>
  153.     Sets the value of the copy prohibit bit. b should
  154.     be either "y" or "n"; y indicates that copies are prohibited. This 
  155.     value will be used on subsequent writes.  The default is to permit 
  156.     copies.
  157.  
  158. at <h>:<m>:<s>:<f>
  159.     Sets the starting atime for the next write to the tape. In 
  160.     general, you should not use this command; dodat will automatically 
  161.     record the correct atime on the tape. Program changes, index 
  162.     changes, seeks, and reads will reset this value.
  163.  
  164. pt <h>:<m>:<s>:<f>
  165.     Sets the starting ptime for the next write to the tape. In 
  166.     general, you should not use this command; dodat will 
  167.     automatically record the correct ptime on the tape.  Program
  168.     changes, index changes, seeks, and reads will reset this value.
  169.  
  170. About DAT Timecode:
  171.  
  172. DAT has a somewhat strange timecode format. A timecode consists of four
  173. values: hours, minutes, seconds, and frames. DAT audio is exactly 100 frames
  174. of audio every three seconds, i.e. 33 1/3 frames per second. However, 
  175. the timecode format allows only integral values of frame numbers. Therefore
  176. the number of frames per second as seen in the timecode will vary, even
  177. though the actual audio frame rate is constant. The first two seconds of 
  178. timecode have 33 frames, numbered 0-32, and the third second has 34 frames,
  179. numbered 0-33. This rule holds throughout the tape, so that for any integer
  180. k, seconds 3k and 3k+1 have 33 frames, and second 3k+2 has 34.
  181.  
  182. If you specify an invalid timecode, dodat will attempt to convert to a valid 
  183. timecode equivalent.  For example, 0:0:0:33 is invalid since there are only 
  184. 33 frames in second 0. dodat will convert this to 0:0:1:0. 
  185.  
  186. What's more, there are multiple types of timecode that can be written on
  187. a DAT. dodat fully supports absolute time ("atime") and program time ("ptime").
  188. Absolute time is the time elapsed since the beginning of the first
  189. valid program on the tape. Program time is the time elapsed since the first
  190. non-zero index within a program. During index 0, which is considered 
  191. inter-program spacing, program time remains 0:0:0:0. There are other types of
  192. timecode, but since dodat does not support them, we do not describe them here.
  193.  
  194. Example DAT scripts
  195.     example1.dat    writes a DAT from three files,
  196.             making separate programs, with proper inter-track
  197.             spacing.
  198.     example2.dat     reads track 1 from a DAT into a disk file
  199.